Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSDictionary 

Inherits From:	NSObject

Conforms To:	NSCoding, NSCopying, NSMutableCopying
NSObject (NSObject)

Declared In:	Foundation/NSDictionary.h 

Class Description

The NSDictionary class declares the programmatic interface to objects that manage immutable associations of keys and values. You use this class when you need a convenient and efficient way to retrieve data associated with an arbitrary key.

A key-value pair within an NSDictionary is called an entry. Each entry consists of an string object that represents the key and another object (of any class) that is that key's value. You establish the entries when the NSDictionary is created, and thereafter the entries can't be modified. (The complementary class NSMutableDictionary defines objects that manage modifiable collections of entries. See the NSMutableDictionary class specification for more information.)

Internally, an NSDictionary uses a hash table to organize its storage and to provide rapid access to a value given the corresponding key. However, the methods defined for this class insulate you from the complexities of working with hash tables, hashing functions, or the hashed value of keys. These methods take key values directly, not their hashed form.

Generally, you instantiate an NSDictionary by sending one of the dictionary... messages to the class object. These methods return an NSDictionary containing the associations specified as arguments to the method. Each key argument is copied and the copy is added to the NSDictionary. Each corresponding value object receives a retain message to ensure that it won't be deallocated prematurely.

NSDictionary's three primitive methodsÐcount and objectForKey: and keyEnumeratorÐprovide the basis for all the other methods in its interface. The count method returns the number of entries in the object, objectForKey: returns the value associated with the given key, and keyEnumerator returns an object that lets you step through entries in the dictionary. 

The other methods declared here operate by invoking one or more of these primitives. The non-primitive methods provide convenient ways of accessing multiple entries at once. The description... methods and the writeToFile:atomically: method cause an NSDictionary to generate a description of itself and store it in a string object or a file.

Exceptions

NSSet implements the encodeWithCoder: method, which raises NSInternalInconsistencyException if the number of objects enumerated for encoding turns out to be unequal to the number of objects in the set. 

Creating and Initializing an NSDictionary

+ (id)allocWithZone:(NSZone *)zone	Creates and returns an uninitialized NSDictionary in zone.

+ (id)dictionary	Creates and returns an empty NSDictionary.

+ (id)dictionaryWithContentsOfFile:(NSString *)path	  
	Creates and returns an NSDictionary from the keys and values found in the file specified by path.

+ (id)dictionaryWithObjects:(NSArray *)objects	Creates and returns an NSDictionary that associates 
forKeys:(NSArray *)keys		objects from the objects array with keys from the keys array. Keys must be strings. Raises NSInvalidArgumentException if the number of objects is not equal to the number of keys.

+ (id)dictionaryWithObjects:(id *)objects	Creates and returns an NSDictionary containing count 
forKeys:(id *)keys		objects from the objects array. The objects are
count:(unsigned int)count		associated with count keys taken from the keys array.

+ (id)dictionaryWithObjectsAndKeys:(id)firstObject, ...
	Creates and returns an NSDictionary that associates objects and keys from the argument list. The list must be in form: object1, key1, object2, key2, ..., nil. Raises NSInvalidArgumentException if any of the keys are nil, or if any of the keys are not of the NSString class.

- (id)initWithContentsOfFile:(NSString *)path	Initializes a newly allocated NSDictionary using the keys and values found in filename.

- (id)initWithDictionary:(NSDictionary *)dictionary
	Initializes a newly allocated NSDictionary by placing in it the keys and values contained in otherDictionary.

- (id)initWithObjectsAndKeys:(id)firstObject,...	Initializes a newly allocated NSDictionary by placing in it the objects and keys from the argument list. The list must be in form: object1, key1, object2, key2, ..., nil. Raises NSInvalidArgumentException if any of the keys are nil, or if any of the keys are not of the NSString class.

- (id)initWithObjects:(NSArray *)objects	Initializes a newly allocated NSDictionary by associating
forKeys:(NSArray *)keys		objects from the objects array with keys from the keys array. Keys must be strings. Raises NSInvalidArgumentException if the number of objects is not equal to the number of keys.

- (id)initWithObjects:(id *)objects	Initializes a newly allocated NSDictionary by associating
forKeys:(id *)keys		count objects from the objects array with an equal
count:(unsigned)count		number of keys from the keys array. Raises NSInvalidArgumentException if any of the objects or keys are nil.

Accessing Keys and Values 

- (NSArray *)allKeys	Returns an NSArray containing the receiver's keys or an empty array if the receiver has no entries.

- (NSArray *)allKeysForObject:(id)object	Finds all occurrences of the value anObject in the receiver and returns an array with the corresponding keys. 

- (NSArray *)allValues	Returns an NSArray containing the dictionary's values, or an empty array if the dictionary has no entries.

- (NSEnumerator *)keyEnumerator	Returns an NSEnumerator that lets you access each of the receiver's keys.

- (NSEnumerator *)objectEnumerator	Returns an NSEnumerator that lets you access each the receiver's values.

- (id)objectForKey:(id)aKey	Returns an entry's value given its key, or nil if no value is associated with aKey.

Counting Entries 

- (unsigned)count	Returns the number of entries in the receiver.

Comparing Dictionaries 

- (BOOL)isEqualToDictionary:(NSDictionary *)other	
	Compares the receiver to otherDictionary. If the contents of otherDictionary are equal to the contents of the receiver, this method returns YES. If not, it returns NO.

Storing Dictionaries 

- (NSString *)description	Returns a string that represents the contents of the receiver.

- (NSString *)descriptionInStringsFileFormat	Returns a string that represents the contents of the receiver. Key-value pairs are represented in a appropriate for use in ª.stringsº files

- (NSString *)descriptionWithLocale:(NSDictionary *)localeDictionary
	Returns a string representation of the NSDictionary object. Included are the key and values that represent the locale data from localeDictionary.

- (NSString *)descriptionWithLocale:(NSDictionary *)localeDictionary
indent:(unsigned int)level	Returns a string representation of the NSDictionary object. Included are the key and values that represent the locale data from localeDictionary. Elements are indented from the left margin by level + 1 multiples of four spaces, to make the output more readable.

- (BOOL)writeToFile:(NSString *)path	Writes a textual description of the contents of the 
atomically:(BOOL)useAuxiliaryFile		receiver to filename. If useAuxiliaryFile is YES, the data is written to a backup file and then, assuming no errors occur, the backup file is renamed to the intended file name.